C++ Interop: API importing and semantics #6358

bricknerb · 2025-11-12T14:58:17Z

This proposal defines the concrete technical mechanisms for C++
interoperability. It builds on the high-level directional agreement of #6254
("Calling C++ Functions") by specifying the precise syntax and semantics for
importing C++ APIs. This includes the import Cpp library "..." and implicitly
importing C++ built-in entities, and the establishment of the Cpp package as
the dedicated namespace for all imported entities.

This PR also includes high level language C++ Interop design and the basics of importing C++ APIs and function calling.
Leaving plenty of TODOs to make it easier to fill in more details in followups.

Part of #4666.

This includes high level design ideas and the basics of importing C++ APIs and function calling. Leaving plenty of TODOs to make it easier to fill in more details in followups.

jonmeow

I think there's an important distinction of implementation versus design... Where you talk about a specific implementation requirement using Clang, I think that's a toolchain design detail. That'd suggest to me that the details are more appropriate for toolchain/docs (implementation) than docs/design (language design).

That is, for our implementation, we have chosen to use Clang and we're making implementation trade-offs based on that. However, if someone chose to build their own Carbon compiler, they should have freedom to choose a C++ compiler that suited them so long as it fit the higher-level language needs.

Also for language design, I think we typically want proposals first, then language design changes (or, put the language design change in with the proposal). But I'm just going to swap myself out for review with zygoloid since that's more of a leads choice, and he's also familiar with what's being done here.

jonmeow

Just highlighting a few things from a read-through, but trying not to get into many details because of the mix of design and implementation here.

docs/design/interoperability/README.md

bricknerb · 2025-11-13T10:41:01Z

I think there's an important distinction of implementation versus design... Where you talk about a specific implementation requirement using Clang, I think that's a toolchain design detail. That'd suggest to me that the details are more appropriate for toolchain/docs (implementation) than docs/design (language design).

That is, for our implementation, we have chosen to use Clang and we're making implementation trade-offs based on that. However, if someone chose to build their own Carbon compiler, they should have freedom to choose a C++ compiler that suited them so long as it fit the higher-level language needs.

Also for language design, I think we typically want proposals first, then language design changes (or, put the language design change in with the proposal). But I'm just going to swap myself out for review with zygoloid since that's more of a leads choice, and he's also familiar with what's being done here.

Thanks Jon!
I've edited this to focus on language design, removing implementation specific parts including the entire TODO section for thunks.

bricknerb · 2025-11-14T08:55:31Z

I think there's an important distinction of implementation versus design... Where you talk about a specific implementation requirement using Clang, I think that's a toolchain design detail. That'd suggest to me that the details are more appropriate for toolchain/docs (implementation) than docs/design (language design).
That is, for our implementation, we have chosen to use Clang and we're making implementation trade-offs based on that. However, if someone chose to build their own Carbon compiler, they should have freedom to choose a C++ compiler that suited them so long as it fit the higher-level language needs.
Also for language design, I think we typically want proposals first, then language design changes (or, put the language design change in with the proposal). But I'm just going to swap myself out for review with zygoloid since that's more of a leads choice, and he's also familiar with what's being done here.

Thanks Jon! I've edited this to focus on language design, removing implementation specific parts including the entire TODO section for thunks.

Waiting for @zygoloid review.

zygoloid

This seems reasonable, but I think there are details here that haven't been through the proposal process, so it'd make sense to add a little pro forma /proposals/p6358.md here and treat this as a proposal so we can give it the weight of being an approved design change.

zygoloid · 2025-11-14T23:52:13Z

docs/design/interoperability/README.md

+The design of Carbon's C++ interoperability is governed by its foundational
+goal: [to be a successor language](/README.md), not merely a language with a
+foreign function interface (FFI). This mandate dictates a design that moves
+beyond the C-style FFI adopted by most modern languages and instead provides
+"seamless, bidirectional interoperability". The objective is to support deep
+integration with existing C++ code, encompassing its most complex features,
+"from inheritance to templates".
+
+This goal has profound implications for the Carbon compiler and language
+semantics. It requires that C++ is not treated as a "foreign" entity. Instead,
+Carbon's semantic model must be _co-designed_ to understand, map, and interact
+with C++'s semantic constructs—including templates, class hierarchies, and
+complex overload resolution—with high fidelity. The interoperability layer must,
+therefore, operate at the semantic analysis level, not just at the linking (ABI)
+level. This document specifies the design of this semantic contract.


I would drop all the double-quotes here. While these quotes are pulled from the main README, I don't think that's worth calling out, especially since we're quoting ourselves.

zygoloid · 2025-11-14T23:52:35Z

docs/design/interoperability/README.md

+compiler. Any operation involving a type that is designated as a C++ interop
+type could invoke the specialized interoperability logic, such as C++ overload
+resolution or operator overload resolution that involves both Carbon and C++
+operator overloads..


Suggested change

operator overloads..

operator overloads.

zygoloid · 2025-11-14T23:54:42Z

docs/design/interoperability/README.md

+4.  A Carbon struct or class containing a C++ interop type as a member (for
+    example, `MyCarbonStruct { x: Cpp.Widget }`).


Do we want this fourth case? It sounds expensive to check whether Carbon classes are compounded from C++ types in general, and I'm not sure we know yet what Carbon struct types would map into in C++, but I don't think it's likely that there'll be C++ operations defined for either case.

Maybe we can narrow this down to just Carbon class types that extend a C++ type?

zygoloid · 2025-11-14T23:56:52Z

docs/design/interoperability/README.md

+This "pervasive" model of C++-awareness is a fundamental design choice. The C++
+semantics are not confined to a specific `unsafe` or `extern "C++"` block; they
+affect any Carbon type that composes them. For example, when the Carbon compiler
+instantiates a _Carbon_ generic type like `MyCarbonVector(Cpp.Widget)`, its type
+system must be aware that the `Cpp.Widget` parameter carries C++-specific rules.
+This mandates that Carbon's own generic system, struct layout logic, overload
+resolution and operator lookup must query the type system for the presence of a
+C++ interop type. If present, Carbon must consider C++ rules when operating over
+C++ interop types. This design prioritizes the goal of a "seamless" and
+"intuitive" user experience.


As above, I'd drop the double-quotes here.

zygoloid · 2025-11-14T23:58:30Z

docs/design/interoperability/README.md

+This syntax is used for both C-style standard libraries and C++ headers:
+
+-   **C Standard Library:**


Suggested change

This syntax is used for both C-style standard libraries and C++ headers:

- **C Standard Library:**

This syntax is used for both standard library headers and user-defined headers:

- **Standard Library:**

I think we should try to avoid mentioning C here.

…ending.

bricknerb · 2025-11-17T12:30:10Z

This seems reasonable, but I think there are details here that haven't been through the proposal process, so it'd make sense to add a little pro forma /proposals/p6358.md here and treat this as a proposal so we can give it the weight of being an approved design change.

I've created a proposal, which assumes the proposal #6254 is accepted.

C++ Interop design details - the basics

aa33a1e

This includes high level design ideas and the basics of importing C++ APIs and function calling. Leaving plenty of TODOs to make it easier to fill in more details in followups.

github-actions bot added the documentation An issue or proposed change to our documentation label Nov 12, 2025

bricknerb marked this pull request as ready for review November 12, 2025 15:04

bricknerb requested a review from a team as a code owner November 12, 2025 15:04

bricknerb requested review from jonmeow and removed request for a team November 12, 2025 15:04

bricknerb mentioned this pull request Nov 12, 2025

Calling C++ Functions #6254

Open

jonmeow reviewed Nov 12, 2025

View reviewed changes

jonmeow requested review from jonmeow and zygoloid and removed request for jonmeow November 12, 2025 17:01

jonmeow reviewed Nov 12, 2025

View reviewed changes

bricknerb added 2 commits November 13, 2025 10:23

Use sentence case for headings

56249f7

Focus on language design and address review comments.

6da998b

zygoloid reviewed Nov 15, 2025

View reviewed changes

bricknerb added 7 commits November 17, 2025 08:58

Avoid mentioning C.

db976ee

Remove double-quotes.

5aec63f

For C++ interop type definition, replace containing a member with ext…

a7efde0

…ending.

Fix double period typo.

1f2f37f

Filling out template with PR 6358

9c59aa1

Fix typo.

a8a3c4f

Add C++ Interop: API importing and semantics proposal

d06da8e

bricknerb requested a review from a team as a code owner November 17, 2025 12:29

bricknerb requested review from chandlerc and removed request for a team November 17, 2025 12:29

bricknerb requested a review from zygoloid November 17, 2025 12:30

bricknerb added proposal A proposal proposal rfc Proposal with request-for-comment sent out labels Nov 17, 2025

bricknerb changed the title ~~C++ Interop design details - the basics~~ C++ Interop: API importing and semantics Nov 17, 2025

		4. A Carbon struct or class containing a C++ interop type as a member (for
		example, `MyCarbonStruct { x: Cpp.Widget }`).

		This syntax is used for both C-style standard libraries and C++ headers:

		- C Standard Library:

C++ Interop: API importing and semantics #6358

Are you sure you want to change the base?

C++ Interop: API importing and semantics #6358

Conversation

bricknerb commented Nov 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jonmeow left a comment

Choose a reason for hiding this comment

Uh oh!

jonmeow left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bricknerb commented Nov 13, 2025

Uh oh!

bricknerb commented Nov 14, 2025

Uh oh!

zygoloid left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bricknerb commented Nov 17, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

bricknerb commented Nov 12, 2025 •

edited

Loading